hotbasicfandomcom-20200213-history
MEMORY Object
The MEMORY object creates a RAM space often called a data "stream" which can be used for about any computing purpose one might think of. MEMORY properties and methods enable creation and manipulation of blocks of data. Please see hotmem.bas for example code. As with FILE and other HotBasic stream objects, read and write methods get or put data from the current .Position and when complete, set the .Position to the first byte after the data transferred. HotBasic opens the flood gates. All LIST properties and methods can be used on MEMORY or STRING objects. And MEMORY properties and methods can be used on any dimensioned STRING, LIST, or ARRAY. Why? We love you. PROPERTIES (Read/Write) * Length - Length in bytes of LIST. ** MemLength = MyMem.Length ** IF MyMem.Length THEN 'Memory is not empty ** MyMem.Length = x 'only if x <= MyMem.Ram * Position - Current position for next read/write ** MyMem.Position = x 'only if x <= MyMem.Length * Size - Length in bytes of LIST Note: .Size and .Length refer to the same property item updated as writes are done. Hence, a reduced .Length can be assigned for a particular purpose, such as saving only an initial portion of the data. However, such a changed .Length property should not be expected to remain unchanged after further programmatic writes. PROPERTIES (Read Only String) * ReadBinStr - (bytes) Same as .ReadStr * ReadLine - Reads line at current position For sequential retrieval of crlf-delimited items from any .Position, .ReadLine should be faster, expecially for long streams, since it does not require the step of locating the item based on index. *ReadStr - (bytes) Reads bytes number of bytes Note: bytes may be a variable, expression or immediate value. PROPERTIES (Read Only Numeric) * Handle - Memory handle of object stream data * ItemCount - Item count of object stream; same as .LineCount * LineCount - Line count of object stream * Pointer - Address of object stream data * Ram - Bytes of memory currently allocated for stream use Note: If more memory is required, it is automatically allocated as write methods add data to the stream object. Use of .Clear or .Close is recommended when computing is completed on large streams to free memory that is not immediately used further by the application. After .Close, the dimensioned stream still exists for further use. * ReadNum (bytes) Reads bytes number of bytes Note: Bytes read are assigned to number which can be any numerical data type. Bytes should generally agree with the destination value length. METHODS - Arguments & Comments * Append - Appends result of one or more string expressions $APPTYPE CONSOLE: $TYPECHECK ON defstr a$, b$ a$ = "HotBasic" b$ = "the Gold Standard" a$.Append space, b$, " for best executables" print a$ PAUSE .Append is faster than the logically equivalent a$ = a$ + space + b$ + " for best exectables" which is done in two steps: create concatenated string which is then assigned to the destination variable (a$ above). * Clear - Clears data and frees allocated RAM if > about 256 bytes. E.g., s$.Clear 'same as s$="" or s$=NULL * Close - Clears data; same as .clear * CopyFrom - (stream, bytes) Copies bytes from stream Note: stream may be a STRING, MEMORY, ARRAY, LIST or FILE. Data copied starts at the .Position property of the source stream. * Decrypt - Decrypts data * Encrypt - Encrypts data Note: an optional key argument -- any numeric expression -- may be used with .Encrypt and .Decrypt. MyMemory.Encrypt key 'code MyMemory.Decrypt key 'same key value as used with .Encrypt * ExtractRes - (resource) Extracts resource to .Position in stream object Note: resource may be (1) Resource(n) where n is an immediate integer or (2) a quoted string for the resource descriptor used in $RESOURCE. * Initialize - (bytes) Allocate object's buffer size to be > bytes. Example: MyMemory.Initialize 1024 sets MyMemory.Length = 0, MyMemory.RAM > 1024, and all bytes = 0. .Initialize is typically used to set a minimum buffer size to use the object's address (@MyMemory) as an argument for a procedure. Notice that, if a procedure (e.g., an API) puts data into MyMemory, the application needs to set MyMemory.Length accordingly to the size of the data inserted, else your application will continue to think that there is no data. * LoadArray - (array) Read array into object stream * LoadFromFile - (filename$) Loads filename$ to current position * LoadFromHandle + (mem_obj_handle, bytes) Read bytes of data from a memory object identified by its handle. If bytes is 0, .LoadFromHandle assumes the data is a text string and uses the LEN function to set bytes to load. If successful, .LoadFromHandle replaces object stream data with memory object data. MyMem.LoadFromHandle mem_obj_handle, bytes Note: a mem_obj_handle is often obtained from the OS. E.g., PRINTER and PRINTDIALOG return such handles in .DevNames and .DevMode properties. $DEFINE dmLogPixels 116 DEFSTR devmode DEFWORD LogPixels PRINTER.Dialog devmode.LoadFromHandle PRINTER.DevMode, 140 devmode.Position = dmLogPixels 'from devmode.inc LogPixels = devmode.ReadNum(2) PRINT "LogPixels = "; LogPixels * MemCopyFrom - (stream, bytes) Copies bytes from object stream to argument stream * MemCopyTo (stream, bytes) Copies bytes from argument stream to object stream Note: .CopyFrom, .MemCopyFrom and .MemCopyTo all copy bytes from the current position of the source stream. However, .CopyFrom writes bytes to the destination current .Position, while .MemCopyFrom and .MemCopyTo both write to .Position = 0 in the destination stream. * Read - (var) Reads var from object stream * ReadUDT - (UDT) Reads UDT from object stream * SaveArray - (array) Writes array from object stream to array * SaveToFile - (filename$) Save MEMORY to filename$ If filename$ exists, filename$ is overwritten. * SaveToStream - (stream) Save MEMORY to stream starting at stream .Position * Seek - (position) Sets .Position; Same as .Position = * Write - (var) Writes var to object stream * WriteBinStr - (string$, bytes) Writes bytes from string$ * WriteLine - (string$) Writes string$ appending CRLF * WriteNum - (var, bytes) Writes var as bytes of data * WriteStr - (string$, bytes) Writes bytes from string$ * WriteUDT - (UDT) Writes UDT to object stream Note: Any dimensioned STRING may utilize any of the above properties and methods. E.g., s$.length is faster than LEN(s$). The former just reads the .Length property; the latter evaluates the length by looking for the first null byte as would be customary for text-only string data.